package com.accedo.achievements.services.ajax;

import net.sf.json.JSONObject;

public interface AchievementService {
	/**
	 * Get the specific achievement's name, score and description by using achievement serial number
	 * @param achi_sn	achievement serial number
	 * @return			JSON format achievement name, score and description<br>
	 * eg. {achi_desc:'this is the achi001 description!', achi_name:'Finish stage 1', achi_score:10}
	 */
	public JSONObject getJsonAchiByAchisn(String achi_sn);
	
	/**
	 * The function deals with the unlocking event and relevant events about badges and campaigns.
	 * <p>after user trigger the unlocking of achievement.
	 * Firstly, add this achievement to the user, if this user has unlocked this achievement before then return,
	 * if it's the first time this user unlocked this achievement, then add the points of this achievement to user,
	 * and invoke badges and campaigns events which includes this achievement.
	 * @param username	user name
	 * @param achi_sn	achievement serial number
	 * @return			JSON format popup<br>
	 * eg. {achi_name:'Finish stage 1', card_sn:'CARD001'}
	 */
	public String unlockAndJsonPopup(String username, String achi_sn);
	
	/**
	 * Get achievements by application sn and user name with two states 'A' and 'B'.
	 * <p>state 'A' means this achievement user has already unlocked,
	 * state 'B' means this achievements this user has not unlocked yet.
	 * @param username	user name
	 * @param app_sn	application serial number
	 * @return			JSON format achievements<br>
	 * eg. {achis:[{achi_sn:'ACHI00101',achi_name:'Finish stage 1',achi_score:'10',achi_state:'A'},
	 * {achi_sn:'ACHI00102',achi_name:'Get 2 magic stones',achi_score:'20',achi_state:'A'}]}
	 */
	public JSONObject getJsonAchisByAppsn(String username, String app_sn);
	
	/**
	 * Return the achievements list with whether user unlocked or not, that belongs to the badge.
	 * <p>badge includes batch of achievements.<br>
	 * This function return the name of achievement and the application it belongs to, and state of the user whether unlocked it or not.
	 * @param badge_sn	badge serial number
	 * @param username	user name
	 * @return			JSON format badgeAchis<br>
	 * eg. {badgeAchis:[{app_sn:'APP001', app_name:'Hungry Harry I', achi_sn:'ACHI00102',
	 *  achi_name:'Get 2 magic stones', state:'true'}]}
	 */
	public JSONObject getJsonAchisByBadgesnAndUsername(String badge_sn, String username);
	
	/**
	 * Return the achievements belongs to the campaign with two state, true and false.
	 * <p>this function return the achievements of the specific campaign,
	 * and with two states based on user.
	 * That 'true' means the user has already unlocked the achievement,
	 * 'false' means the user has not unlocked it yet.
	 * @param camp_sn	campaign serial number
	 * @param username	user name
	 * @return			JSON format campAchis<br>
	 * eg. {campAchis:[{app_sn:'APP003', app_name:'Black Jack Pirates I', achi_sn:'ACHI00303',
	 *  achi_name:'Register email', state:'false'}]}
	 */
	public JSONObject getJsonAchisByCampsnAndUsername(String camp_sn, String username);
}
